What

Adds agentex.lib.sdk.utils.webhooks.handle_webhook — a reusable helper an agent calls from a forward-route handler (a @acp.post(...) route that the server's /agents/forward/name/{agent}/{path} ingress proxies to).

It does, agent-side via adk:

• shape the payload (generic, or GitHub/Gitea PR → clean title+body+diff prompt),
• resolve params — inline, or fetched from a params_source URL (config-by-id; the platform's config-resolve endpoint),
• session continuity — get-or-create a task on a stable session key so repeat events (PR opened/synchronize/…) fold into one task,
• dispatch the turn (sync message/send returns the reply inline; async event/send, with optional wait to poll),
• stamp canonical task_metadata (channel/peer_id/sender) plus any source-returned metadata (which can't override the canonical fields).

Why

Triggering an agent from a webhook is already supported via the forward mechanism (which has built-in GitHub/Slack signature auth). This helper provides the shaping/resolve/dispatch convenience on that supported path instead of a parallel ingress, so an agent's webhook handler is ~10 lines.

Before — every agent hand-writes the full pipeline in its handler: shape the raw payload into a prompt, fetch+map the config, hash a stable session key, get-or-create the task, dispatch, then dig the reply back out of the message list. Each agent re-implements the edge cases (diff truncation, sync vs async, id-less messages) and gets them wrong in its own way.

After — the same five steps become keyword arguments; the messy implementation lives once in webhooks.py:

@acp.post("/github-pr")
async def github_pr(request: Request):
    body = await request.json()
    result = await handle_webhook(
        agent_name="my-agent",
        payload=body,
        acp_type="sync",
        shaper="github_pr",
        params_source="https://<host>/public/v5/agent_configs/<id>/resolve",
        params_source_headers={"x-api-key": ..., "x-selected-account-id": ...},
        wait=True,
    )
    return {"task_id": result.task_id, "reply": result.reply}

Config-by-id is ingress-independent: point params_source at the platform's config-resolve endpoint (the scaleapi GET /v5/agent_configs/{id}/resolve server-side counterpart) and the resolved params are forwarded opaquely to task/create.

Design notes (open-source SDK)

This module ships in the open-source SDK, so two things were kept deliberate:

• No secrets / internal coupling. Credentials come from the caller via params_source_headers (docstring uses ... / <host> placeholders). It shapes only public webhook formats (GitHub/Gitea/Slack) and forwards opaque params; the config-resolve endpoint is referenced generically, not by an internal URL. Self-contained leaf module (adk + stdlib).
• Formats data, doesn't dictate behavior. shape_github_pr emits facts only (title / action / URL / description / diff) — no "review this PR" instruction is baked in. The actual task lives in the config's system_prompt, not the helper. The opinionated parts (shaper enum generic/github_pr; MAX_BODY_CHARS/MAX_DIFF_CHARS constants) are opt-in conveniences over a fully-generic base — shaper="generic" + inline params sidesteps both, so nothing traps the user. (fetch is injectable; shaper is currently a closed enum.)

Testing

• 14 unit tests (tests/lib/test_webhooks.py): session-key folding, generic + GitHub-PR shaping, params/config-by-id resolution (envelope + bare-object + error), and handle_webhook sync/async with adk mocked. ruff clean.

🤖 Generated with Claude Code

Greptile Summary

This PR adds agentex.lib.sdk.utils.webhooks.handle_webhook, a reusable helper for forward-route handlers that consolidates the five-step pipeline (shape → resolve params → get-or-create task → dispatch → extract reply) that every webhook-driven agent was previously hand-rolling.

• Payload shaping: render_generic and shape_github_pr convert raw webhook bodies into a structured prompt, with peer_id-based session continuity so repeated PR events fold into one task instead of spawning new ones.
• Params resolution: supports inline params or a remote params_source URL; resolved params are forwarded opaquely to task/create, and source-returned metadata is merged onto the task (canonical fields win).
• Async reply polling: _await_reply snapshots pre-event message ids and count so a reused task's prior reply is never returned as the new one; id-less messages are handled via positional boundary.

_{Reviews (7): Last reviewed commit: "Merge branch 'next' into dm/sdk-webhook-..." | Re-trigger Greptile}